{
"cells": [
{
"cell_type": "markdown",
"id": "cell-0",
"metadata": {},
"source": [
"# Geodetic Coordinates\n",
"\n",
"This tutorial is about the `satkit.itrfcoord` data type — how to describe a **specific point** on or near the Earth's surface and convert between geodetic and Cartesian representations of that point.\n",
"\n",
"> For the abstract definition of the ITRF reference frame, and for rotating vectors between ITRF and other frames (GCRF, TEME, ...), see the **Coordinate Frames** tutorial.\n",
"\n",
"All points here live in the **International Terrestrial Reference Frame (ITRF)** — the Earth-fixed, Earth-rotating frame used in geodesy and satellite operations. `satkit.itrfcoord` represents a position in this frame and provides conversions between:\n",
"\n",
"- **Geodetic coordinates**: latitude, longitude, and altitude above the WGS-84 ellipsoid (ellipsoid-normal, *not* geocentric latitude)\n",
"- **Cartesian coordinates**: a 3-element (x, y, z) vector in meters with origin at Earth's center of mass\n",
"- **Local tangent planes**: East-North-Up (ENU) and North-East-Down (NED) for range/bearing-style computations near a reference point\n",
"- **Geodesic distances**: great-circle-equivalent distances along the WGS-84 ellipsoid between two `itrfcoord` values\n",
"\n",
"This tutorial demonstrates constructing coordinates from geodetic parameters, converting to and from Cartesian vectors, and computing distances between locations."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cell-1",
"metadata": {
"execution": {
"iopub.execute_input": "2026-04-05T17:41:26.475723Z",
"iopub.status.busy": "2026-04-05T17:41:26.475489Z",
"iopub.status.idle": "2026-04-05T17:41:26.521630Z",
"shell.execute_reply": "2026-04-05T17:41:26.521363Z"
}
},
"outputs": [],
"source": [
"import satkit as sk\n",
"\n",
"# Specify a coordinate via Geodetic latitude & longitude (if altitude is left out, default is 0\n",
"boston = sk.itrfcoord(latitude_deg=42.14, longitude_deg=-71.15)\n",
"\n",
"# Denver, CO is at a higher altitude; altitude is specified in meters\n",
"denver = sk.itrfcoord(latitude_deg=32.7392, longitude_deg=-104.99, altitude=1600)\n",
"print(f'Denver = {denver}')\n",
"\n",
"# Get the Cartesian vector for Denver\n",
"print(f'Denver vector coordinate is {denver.vector}')\n",
"\n",
"# Create a duplicate of the Denver coordinate, using vector as input\n",
"denver2 = sk.itrfcoord(denver.vector)\n",
"print(f'Denver created from Cartesian is {denver2}')"
]
},
{
"cell_type": "markdown",
"id": "cell-2",
"metadata": {},
"source": [
"## Creating Coordinates\n",
"\n",
"Coordinates can be created from geodetic parameters (latitude, longitude, altitude) or from a Cartesian position vector. The altitude defaults to 0 (on the ellipsoid surface) if not specified."
]
},
{
"cell_type": "markdown",
"id": "cell-3",
"metadata": {},
"source": [
"## Geodesic Distance\n",
"\n",
"The `geodesic_distance` method computes the shortest path between two points along the surface of the WGS-84 ellipsoid, returning the distance in meters along with the initial and final headings of the path."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cell-4",
"metadata": {
"execution": {
"iopub.execute_input": "2026-04-05T17:41:26.539812Z",
"iopub.status.busy": "2026-04-05T17:41:26.539666Z",
"iopub.status.idle": "2026-04-05T17:41:26.541987Z",
"shell.execute_reply": "2026-04-05T17:41:26.541796Z"
}
},
"outputs": [],
"source": [
"import satkit as sk\n",
"\n",
"newyork = sk.itrfcoord(latitude_deg=40.7128, longitude_deg=-74.0060)\n",
"destinations = [\n",
" {'name': 'London', 'latitude_deg': 51.5072, 'longitude_deg': -0.1276},\n",
" {'name': 'Paris', 'latitude_deg': 48.8566, 'longitude_deg': 2.3522},\n",
" {'name': 'Toronto', 'latitude_deg': 43.6532, 'longitude_deg': -79.3832},\n",
" {'name': 'Tokyo', 'latitude_deg': 35.6763, 'longitude_deg': 139.65},\n",
" {'name': 'Sau Paulo', 'latitude_deg': -23.5558, 'longitude_deg': -46.6396}\n",
"]\n",
"for dest in destinations:\n",
" destcoord = sk.itrfcoord(latitude_deg=dest['latitude_deg'], longitude_deg=dest['longitude_deg'])\n",
" # Distance, start, and end heading along great circle to destination coordinate\n",
" dist, _heading_start, _heading_end = newyork.geodesic_distance(destcoord)\n",
" print(f'New York to {dest['name']} distance is {dist/1e3:.0f} km')\n"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.14.0"
}
},
"nbformat": 4,
"nbformat_minor": 2
}